import {Meta} from '@storybook/addon-docs/blocks';

<Meta title="Guide/Vue Composition API" />

# Vue Composition API

Begining with OJS, OMP, and OPS version 3.5.0 we migrated our ui-library to Vue3, which introduces the new [Composition API](https://vuejs.org/guide/introduction.html#composition-api) as a more flexible alternative to the existing Options API.

## Composition API

The Composition API builds on exactly the same principles as the Options API that we are used to from Vue 2. State management still consists of **state** and **computed** properties and **methods** that update the **state**. Only the syntax is more flexible.

The new syntax might take a bit of getting used to, but it will reward us is with significantly better flexibility compared to mixins, which is very handy in a complex application like we have.

The best learning source is Vue.js [documentation](https://vuejs.org/guide/introduction.html), where you can easily explore syntax differences between the Options API and the Composition API.

## Composables

Composables are replacements for mixins. More details to come about the composables that we provide instead of existing mixins. In general these will be useful to handle all common tasks, like interacting with API, translation or manupulating forms.

## How to organise the code

Even though it seems at first glance that the Composition API is lacking organizational structure, it actually gives the possibility to organise the code by individual features. Every feature usually consists of some state, computed properties and methods. A good example is `SubmissionsPageStore.js`.

Also it should be easy to quickly understand how the Page works when reading the business logic in store. If it's too long or/and contains long functions, it's an indication that some of the features should be moved to individual feature composables. These can be imported to the store and connected with the rest of the features in the store. This helps to get a good understanding of how things works together and it's always possible to dive in into details in individual composables if needed.

## Refs vs reactive

If you want to dive deep and understand all the details of using `ref()` vs `reactive()` when creating reactive state in the Composable API, you can check out its [official documentation](https://vuejs.org/guide/essentials/reactivity-fundamentals) or a detailed [blog post](https://mokkapps.de/blog/ref-vs-reactive-what-to-choose-using-vue-3-composition-api).

But it's not really necessary, as we follow [official recommendations](https://vuejs.org/guide/essentials/reactivity-fundamentals#limitations-of-reactive), which align with my personal experience as well, which is just to always use `ref()` when defining state.

```javascript
import {ref} from 'vue';

// defining state
const isLoading = ref(false);
const items = ref([]);

// modifying the state, using the .value
items.value.push({title: 'a'});
isLoading.value = true;
```
